logger.error(java.text.MessageUtil.format( java.util.PropertyResourceBundle.getBundle( "org.scribble.protocol.Messages").getString( "_CHOICE_ROLE"), "from"), obj.getProperties());
There is a generic logging API within the Scribble
framework that can be used for reporting errors,
warnings, information or debuging details.
This API is org.scribble.common.logging.Journal.
The methods generally take two parameters, a message
and a property map. The message is simply a description
of the issue being reported. The property map contain
specific details about the issue being reported.
For example, when the parser detects a problem, it
can report the nature of the problem, and provide the
location of the issue in the source file.
To enable errors reported from the Scribble parser
and validation modules, in a number of different
languages, internationalization should be used.
The following code fragment provides an example
of how internationalization can be achieved, using
parameterised messages.
logger.error(java.text.MessageUtil.format( java.util.PropertyResourceBundle.getBundle( "org.scribble.protocol.Messages").getString( "_CHOICE_ROLE"), "from"), obj.getProperties());
The main message content is obtained from a
properties file, with the name being supplied
as the parameter to the getBundle
method. The property file must be placed
the correct package within the
src/main/resources folder, to
ensure the properties are correctly packaged
by maven.
The messages within the property files can have
values that include parameters. Parameters are
numbered in sequential order, and defined between
curly braces (e.g. {n} where 'n' is the number).
For example,
_EXISTING_DECLARATION=Declaration already exists for name {0}
This message only has a single parameter.
In the previous code fragment, the
MessageUtil.format()
method takes the message as the first parameter,
and a variable comma separated list of strings as the parameter values
to be substituted in the message. So in the
code fragment, the value "from"
would be substituted in the {0}
parameter of the _CHOICE_ROLE
message, and then reported to the journal.
The object model representation of a Protocol is defined using classes within
the org.scribble.protocol.model package. All model classes
are derived from a common ModelObject class, which defines
common properties of all components in the model.
Where object model components are contained by another model component, we use
a special list implementation called ContainmentList. This
implementation maintains a reference to its containing parent model object, making
it easier to navigate up the protocol object model hierarchy.
The Protocol Parser is responsible for converting the textual Scribble
notation into an object model representation.
package org.scribble.protocol.parser;
...
public interface ProtocolParser {
public org.scribble.protocol.model.ProtocolModel parse(java.io.InputStream is,
org.scribble.common.logging.Journal journal);
}
The parser only has a single method, which takes the input stream containing
the text based representation of the Scribble protocol, and a Journal
for error reporting purposes.
If the Protocol has valid syntax, then a ProtocolModel
will be returned representing the protocol in object model form.
The protocol projection component is used to derive a local protocol representation,
associated with a nominated role, from a global protocol representation.
The interface for this component is,
package org.scribble.protocol.projection;
...
public interface ProtocolProjector {
public ProtocolModel project(ProtocolModel model, Role role,
Journal journal);
}
This method takes the global protocol model, the role to be
projected, and a journal for reporting any errors. The
result is either a local representation of the protocol
model for the specified role, or null if a failure occurred.
The validation manager, when used in a OSGi runtime
environment, will listen for the activation of any
implementations of the
org.scribble.protocol.validation.Validator
interface.
This means that the validation of any model can be
performed using the
org.scribble.protocol.validation.ValidationManager,
rather than having to obtain instances of
multiple implementations of the Validator
interface.
When the ValidatorManager is used
outside of an OSGi environment, it is necessary for the
validators to be added to the manager by other means.
One of the default validation implementations is
org.scribble.protocol.validation.rules.DefaultProtocolComponentValidator.
This class is derived from a generic based class that validates
supplied protocol models by visiting the component objects
within the model, and invoking a specific 'validation rule'
based on the type of the model object.
This default implementation is used to provide the basic
validation rules for the model components. For example,
to ensure that the roles defined within an interaction have
been previously declared within the scope containing the
interaction.
The Scribble tools provide a mechanism for exporting a Scribble Protocol
object model to other representations. This module has the following
interface,
package org.scribble.protocol.exporter;
...
public interface ProtocolExporter {
public String getId();
public String getName();
public void export(ProtocolModel model, Journal journal, java.io.OutputStream os);
}
Each 'exporter' implementation defines an id and more descriptive. The id
can be used to lookup the implementation from the ProtocolExportManager,
whereas the name can be used as a descriptive name for display to users.
The export method takes the protocol model to be
exported, the journal where to report errors, and the output stream which
will be the destination for the exported representation.
The org.scribble.protocol bundle contains a default
exporter to convert the Scribble object model representation into a text
based representation. The 'id' for this implementation is txt.
Another export module is the org.scribble.protocol.export.monitor.
This implementation produces an XML based finite state machine representation
of the protocol, for use by the Scribble Protocol Monitor.
The Scribble Protocol Monitor provides a runtime component that can
observe messages being sent and received by an endpoint application,
assuming a particular role within a protocol, and ensure that it
conforms to the expected behaviour.
TO BE DOCUMENTED